<h1>NewFunction2</h1>

<p>The NewFunction2 action is used to create a user-defined function. It was added in Flash 7 to improve the performance of function calls by allowing 
variables to be pre-loaded to a set of up to 256 internal registers and controlling 
the loading of pre-defined variables such as <em>_root</em>, <em>_parent</em>, 
<em>_global</em>, <em>super</em>, <em>this</em> and the <em>arguments</em> array 
containing the arguments passed to the function.</p>

<table>

<tr>
<th nowrap>Field Name</th>
<th>Type</th>
<th>Size</th>
<th>Description</th>
</tr>

<tr>
<td nowrap valign="top"><a name="ActionType">Type</a></td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">8</td>
<td>Identifies the action when it is encoded.</td>
</tr>

<tr>
<td nowrap valign="top"><a name="ActionLength">Length</a></td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">16</td>
<td>The number of bytes in the rest of the encoded action. The total number of
bytes in the encoded action is Length+3.</td>
</tr>

<tr>
<td nowrap valign="top">name</td>
<td nowrap valign="top">String</td>
<td nowrap valign="top" align="right">[n]</td>
<td>A string defining the name of the function.</td>
</tr>

<tr>
<td nowrap valign="top"><a name="ActionLength">argumentCount</a></td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">16</td>
<td>The number arguments supplied to the function.</td>
</tr>

<tr>
<td nowrap valign="top">registerCount</td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">8</td>
<td>The number of registers, up to 256, to allocate for storing variables.</td>
</tr>

<tr>
<td nowrap valign="top">optimizations</td>
<td nowrap valign="top">unsigned bit</td>
<td nowrap valign="top" align="right">16</td>
<td>A code consisting of a number of flags that control the execution environment 
for the function.</td>
</tr>

<tr>
<td nowrap valign="top">arguments</td>
<td nowrap valign="top">RegisterVariables</td>
<td nowrap valign="top" align="right">[argumentCount]</td>
<td>An array of RegisterVariables containing the names of the arguments 
and whether they will be assigned to internal registers or defined in memory as 
local variables. The order of the RegisterVariables in the argument 
array indicate the order in which the values will be popped off the stack when 
the function is executed. The fist argument is popped from the stack first.</td>
</tr>

<tr>
<td nowrap valign="top"><a name="ActionLength">actionsLength</a></td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">16</td>
<td>The number bytes following which contain encoded actions that define the 
body of the function.</td>
</tr>

<tr>
<td nowrap valign="top">actions</td>
<td nowrap valign="top">Action</td>
<td nowrap valign="top" align="right">[n]</td>
<td>An array containing the actions that are executed.</td>
</tr>

</table>

<p>The optimization attribute is a compound code, containing a number of flags that 
control how the environment of the function is initialised. Controlling the pre-defined 
variables that are created and pre-loading them into registers can significantly 
improve performance.</p>

<table>
<tr>
<th align="left">Environment</th>
<th align="left">Description</th>
</tr>

<tr><td>CreateSuper</td><td>Create and initialise the <em>super</em> variable with the parent class of the function.</td></tr>
<tr><td>CreateArguments</a></td><td>Create the <em>arguments</em> variable which contains the arguments passed to the function.</td></tr>
<tr><td>CreateThis</td><td>Create the and initialise the <em>this</em> variable with the object.</td></tr>
<tr><td>LoadThis</td><td>Pre-load the <em>this</em> variable into register number 1.</td></tr>
<tr><td>LoadArguments</td><td>Pre-load the <em>parent</em> variable into register number 2.</td></tr>
<tr><td>LoadSuper</td><td>Pre-load the <em>super</em> variable into register number 3.</td></tr>
<tr><td>LoadRoot</td><td>Pre-load the <em>_root</em> variable into register number 4.</td></tr>
<tr><td>LoadParent</td><td>Pre-load the <em>_parent</em> variable into register number 5.</td></tr>
<tr><td>LoadGlobal</td><td>Pre-load the <em>_global</em> variable into register number 5.</td></tr>
</table>

<p>The register numbers that the predefined variables, <em>this</em>, <em>parent</em>, 
<em>super</em>, <em>_root</em>, <em>_parent</em> and <em>_global</em> are assigned 
to are fixed. When specifying which of the functions arguments are also assigned 
to registers it is important avoid these locations otherwise the variables will 
be overwritten.</p>

<p>User-defined functions are also used to create methods for user-defined objects. 
The name of the function is omitted and the function definition is assigned to a 
variable which allows it to be referenced at a alter time. See the example below.</p>

<p>The arguments supplied to the function can be referenced by the name supplied 
in the arguments array.</p>

<p>All the action objects added are owned by the function. They will be deleted 
when the function definition is deleted.</p>

<h2>History</h2>

<p>The NewFunction2 action represents the ActionDefineFunction2 action of the 
Macromedia Flash (SWF) File Format Specification. It was introduced in Flash 7.</p>
